<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>geometry-utils.js - Documentation</title>

    <script src="scripts/prettify/prettify.js"></script>
    <script src="scripts/prettify/lang-css.js"></script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
</head>
<body>

<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
  <div class="navicon"></div>
</label>

<label for="nav-trigger" class="overlay"></label>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="LabelElement.html">LabelElement</a></li><li><a href="module-labeling-utils-GridPolygon.html">GridPolygon</a></li><li><a href="module-mgrs-utils-NonPolarGridZone.html">NonPolarGridZone</a><ul class='methods'><li data-type='method'><a href="module-mgrs-utils-NonPolarGridZone.html#toPolygon">toPolygon</a></li><li data-type='method'><a href="module-mgrs-utils-NonPolarGridZone.html#toPolyline">toPolyline</a></li></ul></li><li><a href="module-mgrs-utils-VisibleGridZone.html">VisibleGridZone</a><ul class='methods'><li data-type='method'><a href="module-mgrs-utils-VisibleGridZone.html#getCenterLabel">getCenterLabel</a></li><li data-type='method'><a href="module-mgrs-utils-VisibleGridZone.html#getLabels">getLabels</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-constants.html">constants</a></li><li><a href="module-geometry-utils.html">geometry-utils</a><ul class='methods'><li data-type='method'><a href="module-geometry-utils.html#~extentToPolygon">extentToPolygon</a></li><li data-type='method'><a href="module-geometry-utils.html#~pointToGeographic">pointToGeographic</a></li><li data-type='method'><a href="module-geometry-utils.html#~polygonToPolyline">polygonToPolyline</a></li><li data-type='method'><a href="module-geometry-utils.html#~toGeographic">toGeographic</a></li><li data-type='method'><a href="module-geometry-utils.html#~toWebMercator">toWebMercator</a></li></ul></li><li><a href="module-labeling-utils.html">labeling-utils</a><ul class='methods'><li data-type='method'><a href="module-labeling-utils.html#~distanceFromMapEdge">distanceFromMapEdge</a></li><li data-type='method'><a href="module-labeling-utils.html#~getScreenSize">getScreenSize</a></li><li data-type='method'><a href="module-labeling-utils.html#~getWidthOfText">getWidthOfText</a></li><li data-type='method'><a href="module-labeling-utils.html#~padZero">padZero</a></li><li data-type='method'><a href="module-labeling-utils.html#~screenDistanceBetweenPoints">screenDistanceBetweenPoints</a></li></ul></li><li><a href="module-mgrs-utils.html">mgrs-utils</a><ul class='methods'><li data-type='method'><a href="module-mgrs-utils.html#~getInterval">getInterval</a></li><li data-type='method'><a href="module-mgrs-utils.html#~handle100kGrids">handle100kGrids</a></li><li data-type='method'><a href="module-mgrs-utils.html#~handleIntervals">handleIntervals</a></li><li data-type='method'><a href="module-mgrs-utils.html#~handleZonePolygon">handleZonePolygon</a></li><li data-type='method'><a href="module-mgrs-utils.html#~processZonePolygons">processZonePolygons</a></li><li data-type='method'><a href="module-mgrs-utils.html#~zonesFromExtent">zonesFromExtent</a></li></ul></li></ul><h3>Externals</h3><ul><li><a href="external-Color.html">Color</a></li><li><a href="external-Extent.html">Extent</a></li><li><a href="external-Font.html">Font</a></li><li><a href="external-Geometry.html">Geometry</a></li><li><a href="external-Graphic.html">Graphic</a></li><li><a href="external-GraphicsLayer.html">GraphicsLayer</a></li><li><a href="external-Map.html">Map</a></li><li><a href="external-Point.html">Point</a></li><li><a href="external-Polygon.html">Polygon</a></li><li><a href="external-Polyline.html">Polyline</a></li><li><a href="external-SpatialReference.html">SpatialReference</a></li><li><a href="external-TextSymbol.html">TextSymbol</a></li></ul>
</nav>

<div id="main">
    
    <h1 class="page-title">geometry-utils.js</h1>
    

    



    
    <section>
        <article>
            <pre class="prettyprint source linenums"><code>/**
 *  @fileOverview Module containing geometry utilities used by GridOverlay widgets.
 *  @author Esri
 */

/**
 *  @module geometry-utils
 *  @description Module containing geometry utilities used by GridOverlay widgets.
 */

define([
  "./constants",
  "esri/geometry/webMercatorUtils",
  "esri/geometry/Point",
  "esri/geometry/Polyline",
  "esri/geometry/Polygon"
], function(
  constants,
  webMercatorUtils,
  Point,
  Polyline,
  Polygon
) {

  return {

    /**
     * Converts any geometry from WebMercator to Geographic, or does nothing if it already is
     * NOTE: Does not modify the input geometry object
     * @param  {external:Geometry} geometry   An esri geometry object
     * @return {external:Geometry}            A geometry oject that is Geographic
     */
    toGeographic: function(geometry) {
      if (geometry.spatialReference.isWebMercator()) {
        return webMercatorUtils.webMercatorToGeographic(geometry);
      }
      return geometry;
    },

    /**
     * Converts any geometry to WebMercator from Geographic, or does nothing if it already is
     * NOTE: Does not modify the input geometry object
     * @param  {external:Geometry} geometry   An esri geometry object
     * @return {external:Geometry}            A geometry oject that is WebMercator
     */
    toWebMercator: function(geometry) {
      if (!geometry.spatialReference.isWebMercator()) {
          return webMercatorUtils.geographicToWebMercator(geometry);
      }
      return geometry;
    },

    /**
     * Converts a geographic latitude to Web Mercator (assumes WGS84)
     * NOTE: This local method is favored over external API methods for better performances
     * @param  {Number} latitude A WGS84 geographic latitude
     * @return {Number} A WGS84 Web Mercator &lt;em>y&lt;/em>
     * @private
     */
    _latitudeToWebMercatorY: function(latitude) {
      var y = latitude;
      var deg180 = constants.GEOGRAPHIC_360 / 2;
      var eRadius = constants.WGS84_EQUATORIAL_RADIUS;
      return (constants.HALF_PI - (2.0 * Math.atan(Math.exp((-1.0 * y) / eRadius)))) * deg180 / Math.PI;
    },

    /**
     * Converts a geographic longitude to Web Mercator (assumes WGS84)
     * NOTE: This local method is favored over external API methods for better performance
     * @param  {number} longitude A WGS84 geographic longitude
     * @return {Number} A WGS84 Web Mercator &lt;em>x&lt;/em>
     * @private
     */
    _longitudeToWebMercatorX: function(longitude) {
      var x = longitude;
      var deg360 = constants.GEOGRAPHIC_360;
      var deg180 = constants.GEOGRAPHIC_360 / 2;
      var eRadius = constants.WGS84_EQUATORIAL_RADIUS;
      return x / eRadius * deg180 / Math.PI - (Math.floor((x / eRadius * deg180 / Math.PI + deg180) / deg360) * deg360);
    },

    /**
     * A point-like geometry object, with x an y properties, and containing the non-normalized x-offset of the point
     * @typedef  module:geometry-utils~GeogprahicPoint
     * @property {Number} x         The longitude
     * @property {Number} y         The latitude
     * @property {Number} offsetX   The &lt;em>x&lt;/em> offset
     */

    /**
     * Converts a geometry Point from WebMercator to Geographic and denotes the &lt;em>x&lt;/em> offset from the range: 180°W => 180°E
     * NOTE: Does not modify the input point object
     * @param  {external:Point} point A geometry Point object
     * @return {module:geometry-utils~GeogprahicPoint} A geographic point object
     */
    pointToGeographic: function(point) {
      var x = point.x;
      var y = point.y;
      var isWebMercator = point.spatialReference.isWebMercator();

      // Set the limits based on whether or not the point is WebMercator or Geographic
      // This is used to calculate the x_offset value
      var westernLimit = isWebMercator ? constants.WEST_WEBMERCATOR_LIMIT : constants.WEST_GEOGRAPHIC_LIMIT;
      var easternLimit = isWebMercator ? constants.EAST_WEBMERCATOR_LIMIT : constants.EAST_GEOGRAPHIC_LIMIT;
      var span360 = isWebMercator ? constants.WEBMERCATOR_360 : constants.GEOGRAPHIC_360;

      // retain how far left/right of int'l dateline the original point is
      var x_offset = 0;

      // fix for x west of int'l dateline
      while (x &lt;= westernLimit) {
        x += span360;
        x_offset -= 1;
      }

      // fix for x east of int'l dateline
      while (x > easternLimit) {
        x -= span360;
        x_offset += 1;
      }

      if (isWebMercator) {
        // convert web mercator point to geographic
        x = this._longitudeToWebMercatorX(x);
        y = this._latitudeToWebMercatorY(y);
      }

      return {
        "x": x,
        "y": y,
        "offsetX": x_offset
      };
    },

    /**
     * Converts an Extent geometry to a Polygon geometry (it does not modify the input point object)
     * &lt;strong>NOTE:&lt;/strong> Unlike the ArcGIS API for JavaScript's method (Polygon.fromExtent), this does not normalize the extent before converting to polygon
     * @param  {external:Extent}   extent  A geometry Extent object
     * @return {external:Polygon}          A geometry Polygon object
     */
    extentToPolygon: function(extent) {
      return new Polygon({
        rings: [[
          [extent.xmin, extent.ymin],
          [extent.xmax, extent.ymin],
          [extent.xmax, extent.ymax],
          [extent.xmin, extent.ymax],
          [extent.xmin, extent.ymin]  // close the polygon
        ]],
        spatialReference: extent.spatialReference
      });
    },

    /**
     * Converts an Polygon geometry to a Polyline geometry
     * NOTE: Does not modify the input polygon object
     * @param  {external:Polygon} polygon   A geometry Polygon object
     * @return {external:Polyline}          A geometry Polyline object
     */
    polygonToPolyline: function(polygon) {
      return new Polyline({
        "paths": polygon.rings,
        "spatialReference":{"wkid": polygon.spatialReference.wkid}
      });
    }

  };
});</code></pre>
        </article>
    </section>




</div>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>
</body>
</html>
